home *** CD-ROM | disk | FTP | other *** search
/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / comm / bbs / msfilter2.lha / MSFilter.doc next >
Text File  |  1997-07-19  |  13KB  |  324 lines
  1. MSFilter 1.1 (c) 1994 by Doug McLean
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. *** Please read this entire doc file, even if you already run MSFilter. ***
  5. *** The configuration file has completely changed, and you will want    ***
  6. *** to fully understand how the new features work before setting it up. ***
  7. *** If you don't read all the docs, you might get unexpected results.   ***
  8.  
  9. Do you feed from a MS-Dos system that sends you an annoying file attach
  10. message for every tick file you get? Or is there someone on one or more
  11. of the echos who you find really annoying and just won't go away??? Are
  12. there message threads that have gotten out of hand, and you don't want
  13. cluttering up your BBS or point? Then try MSFilter.
  14.  
  15. MSFilter is a fido packet filter. What is does is examine packets in your
  16. inbound, and remove from each packet any messages that are:
  17.  
  18.       - from anyone you want filtered,
  19.       - to anyone you want filtered,
  20.       - about any subject you want filtered,
  21.  
  22. but, MSFilter will NOT filter messages:
  23.  
  24.       - from anyone you don't want filtered,
  25.       - to anyone you don't want filtered,
  26.       - about any subject you don't want filtered.
  27.  
  28. With this release, MSFilter is pretty configurable as to what is and is
  29. not filtered (although, as with any program, there is always room for
  30. improvement :-).
  31.  
  32. The filtering is done before you import your mail, so filtered messages
  33. aren't even imported (as opposed to some filters that delete the messages
  34. once they have been imported, leaving "holes" in your message areas).
  35. MSFilter looks only at packets, so it doesn't care what you run for a
  36. tosser or BBS or mailer.
  37.  
  38. For example, when my feed sends along tick files, he also send an empty
  39. file attach message. Since I don't want these messages cluttering up my
  40. netmail area, I filter any messages from Tick v2.10.
  41.  
  42.  
  43. Legal Stuff
  44. ~~~~~~~~~~~
  45. I forgot this section in the initial release, so here it is now.
  46.  
  47. Use MSFilter at your own risk. If it works well for you, great! If it
  48. doesn't, or if it causes un-expected side effects, or it it totally
  49. messes up your system, or does anything else you don't like, tough!
  50. That is your problem, not mine.
  51.  
  52. I don't expect you to have any problems with MSFilter, it works as
  53. expected here. But if you do have problems, please don't blame me for
  54. them. But please DO send me full info on any bugs you find (hopefully,
  55. there are none :-).
  56.  
  57. MSFilter is copyright by me (Doug McLean). You may distribute it as you
  58. wish, as long as all files are intact within the original archive, and
  59. as long as you do not profit by distributing it. You may not alter any of
  60. the files in the archive in any way.
  61.  
  62.  
  63. Setting it up (the config file)
  64. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65. Place the executable and config file wherever you want (I have mine in
  66. Doors:MSFilter/).
  67.  
  68. Edit the config file to suit your needs. My config file is:
  69.  
  70. ;Filter messages from these people
  71. <Tick v2
  72. <Bill Beogele
  73. ;Filter messages to these people
  74. >Bill Beogele
  75. ;Some subjects to filter
  76. =w h i n e
  77. =beogis
  78. =stalked by james hastings
  79. ;But always keep messages addressed to these people
  80. +Doug McLean
  81. +Mike Mossman
  82. +Tim Locke
  83. ;And always keep messages from these people
  84. &Doug McLean
  85. &Mike Mossman
  86. &Tim Locke
  87. &Moderator
  88. ;And always keep these subjects
  89. $msfilter
  90.  
  91. There should be no spaces before or after the names (or the space will
  92. become part of the string to check for!). Do not leave any blank lines
  93. either at the beginning or the end of the config file!!!
  94.  
  95. The first character on each line must be one of the following:
  96.  
  97.    ; A comment line. This does not affect filtering in any way
  98.    < filter all messages from this person
  99.    > filter all messages to this person
  100.    = filter all messages that have a subject line that contains
  101.      the specified string
  102.    + never filter messages to this person, regardless of other
  103.      filtering criteria
  104.    & never filter messages from this person, regardless of other
  105.      filtering criteria
  106.    $ never filter messages whose subject line contains this string
  107.      regardless of other filtering criteria
  108.  
  109. Except for the subject check, the string to filter is checked against the
  110. appropriate field (to/from) starting at the beginning of the string and
  111. only for the length of the specified filter string.
  112.  
  113. So in the above example config file, messages from Tick v2.0, Tick v2.10,
  114. Tick v26.Beta4 etc will be filtered, while messages from Tick v will not.
  115. If you specify:
  116.  
  117. <Bill
  118.  
  119. all messages from anyone whose first name is Bill will be filtered, so
  120. be careful with what you specify!
  121.  
  122. With subject filtering (and keeping), any subject that contains the
  123. specified string is filtered (or kept). So if the config file contains:
  124.  
  125. =test
  126.  
  127. "testtube", "echo test", and "abctestdef" will all be filtered.
  128.  
  129. Now, in the above config file all messages to and from anyone whose name
  130. starts with Bill Beogele are filtered. But, if someone named Moderator
  131. sends him a message, then that message will not be filtered, since the
  132. config file specifies that messages from anyone named Moderator should
  133. never be filtered. In the same way, if someone whose name starts with
  134. Bill Beogele send Doug McLean a message, then it won't get filtered,
  135. since messages to Doug McLean are never filtered.
  136.  
  137. Again looking at the above config file, if Bill Beogele send anyone
  138. a message about MSFilter, that message won't get filtered because the
  139. string msfilter is a "keep" subject.
  140.  
  141. See the section "What happens when it runs" for more info on when the
  142. comparisons are made.
  143.  
  144. Note that the comparisons are NOT case sensitive, so Tick is the same as
  145. tick is the same as TICK.
  146.  
  147. Also note that your config file may have a maximum of 50 names in each
  148. catagory. This 50 name limit is for each catagory (not a total of 50),
  149. so you can filter 50 from names, 50 to names, and 50 subjects, and keep 50
  150. from names, keep 50 to names, and keep 50 subjects. This should be enough
  151. for anyone's needs. If you exceed this limit, you will get a warning in the
  152. log file. Note that the 50 name limit for each catagory implies that you
  153. cannot be sure of keeping messages for every user on your BBS, unless you
  154. have very few users. The more strings you specify in each catagory,
  155. the slower MSFilter will run.
  156.  
  157. You *must* specify at least 3 characters for each string you want to check
  158. (4 characters if you count the filter type character). MSFilter will not
  159. check messages against strings with less than 3 characters. 
  160.  
  161. Also note the following restrictions on field lengths in standard fido 
  162. packed messages:
  163.  
  164.      To field     : 36 bytes including null terminator
  165.      From field   : 36 bytes including null terminator
  166.      Subject field: 72 bytes including null terminator
  167.  
  168. Strings in the config file (except comments) should not exceed these
  169. limits. Comments should not exceed 78 characters.
  170.  
  171. You don't need to have something in every catagory if you don't
  172. want, your entire config file might be:
  173.  
  174. <Bill Beogele
  175.  
  176. if that is all you want.
  177.  
  178. If your config file has more than one or two lines, I suggest you set it
  179. up in sections like the above example, It is easier to change that way, and
  180. besides, it will look nicer in the log file.
  181.  
  182.  
  183. Running MSFilter
  184. ~~~~~~~~~~~~~~~~
  185. Once it is set up, all you have to do is run MSFilter on incomming packets
  186. before you import mail. I do this in the aftersession batch file for
  187. TrapDoor. Since MSFilter works on PACKETS, and NOT on bundles, you will
  188. have to un-archive any bundles if you want MSFilter to process them. Here
  189. is the appropriate section from my aftersession script (not my full
  190. aftersession, it would contain a lot of unrelated stuff):
  191.  
  192. .key who/a,baud/a
  193. .bra [
  194. .ket ]
  195. failat 99
  196. waittask CoProcess_<<3>>
  197. echo >>logs:MSFilter.log "####################### Fido session with +[who]+"
  198. date >>logs:MSFilter.log
  199. if "[who]" eq "1:255/1"
  200.  cd inbound:
  201.  list >t:msf.script ????????.(mo|tu|we|th|fr|sa|su)? lformat="rx xarc x %n"
  202.  execute t:msf.script
  203.  delete t:msf.script
  204.  delete ????????.(mo|tu|we|th|fr|sa|su)?
  205.  doors:MSFilter/MSFilter inbound: logs: doors:MSFilter/MSFilter.cfg
  206. endif
  207. dmc process
  208.  
  209. Lines 1-3: This is for command line options to the aftersession script.
  210.            The line that calls the aftersession in my trapdoor.cfg is:
  211.  
  212.            AFTERSESSION "execute dlgconfig:batch/aftersession %n %B"
  213.  
  214. Line 4: Use FAILAT to make sure an error won't abort the script (maybe there
  215.         are no packets or bundles?).
  216.  
  217. Line 5: I make sure that the rest of the script won't run while my tosser
  218.         is already running. Instead, the script waits until the tosser
  219.         is finished. I don't need my tosser and MSFilter fighting
  220.         over packets! If your tosser doesn't run in the background,
  221.         you shouldn't need to wait for it...
  222.  
  223. Lines 6 & 7: A little extra logging for the MSFilter.log file.
  224.  
  225. Line 8: If last session was with my main feed, then do the following.
  226.         Otherwise, go to the line following the ENDIF.
  227.  
  228. Line 9: CD to where the inbound bundles and packets are.
  229.  
  230. Line 10: Make a batch file to take apart any bundles and extract the
  231.          packets that they contain...
  232.  
  233. Line 11: ... and execute the batch file ...
  234.  
  235. Line 12: ... and delete the batch file once it exits.
  236.  
  237. Line 13: Since the packets have been extracted from the bundles, delete
  238.          the bundles or else your tosser will want to take them apart again!
  239.  
  240. Line 14: Have MSFilter process the packets.
  241.  
  242. Line 15: End if the if block. The above if block would have been skipped
  243.          after a connect with anyone other than my main feed.
  244.  
  245. Line 16: Finally, process the mail as usual.
  246.  
  247. Sorry for the step by step analysis, but it occured to me that some of
  248. you may be newer to the Amiga than many of us, and not entirely familiar
  249. with AmigaDos batch files...
  250.  
  251. The MSFilter command line is:
  252.  
  253. path/MSFilter inbound_directory: log_directory: path/config_file_name
  254.  
  255. The inbound: and log: directories MUST end in : or /. The config file
  256. is the full path and file name (allowing you to specify different
  257. config files, perhaps based on who the last session was with).
  258.  
  259. After you have run MSFilter, run your tosser. I use DLGMail, but it doesn't
  260. matter what tosser (or BBS software) you use. All messages that were not
  261. filtered will be imported as usual.
  262.  
  263.  
  264. IMPORTANT
  265. ~~~~~~~~~
  266. After setting up MSFilter, be sure to check the log file regularly (at least
  267. for a while) to make sure that you have configured it corectly. MSFilter
  268. will log exactly what it thinks it should and should not filter. If you
  269. have problems, check the log file and compare it with your config file.
  270. You may have an extra space at the end of a line.
  271.  
  272. If you still have problems, file attach me both your log file and your
  273. config file, and I'll see what the problem is.
  274.  
  275.  
  276. What happens when it runs
  277. ~~~~~~~~~~~~~~~~~~~~~~~~~
  278. First, MSFilter reads the config file. Then, it checks the specified
  279. inbound directory for packets. All packets in the inbound directory will
  280. be processed.
  281.  
  282. For each packet, MSFilter builds a temporary file, to which the packet
  283. header and all non-filtered messages are copied. Filtered messages are
  284. printed to the log file instead of the temporary file.
  285.  
  286. When checking a packet, each message is checked in order. If a message
  287. is to someone you specified you want to keep messages for (+ in the config
  288. file), is from someone you want to keep messages from (& in the config
  289. file), or if the subject field contains a keep string ($ in the config
  290. file), the filtering checks are skipped, and the message kept.
  291.  
  292. If the message does not pass the above tests, then the to, from, and
  293. subject fields (>, <, and = in the config file) are checked against the
  294. appropriate lines in the config file. If the message fails any of these
  295. checks, then it is filtered, and copied to the log file as text. The
  296. reason the message was filtered is logged as well.
  297.  
  298. If a packet does not contain any messages to be filtered, the temporary
  299. file is deleted.
  300.  
  301. If some of the messages were filtered, the original packet is deleted and
  302. the temporary file renamed to the original packet name.
  303.  
  304. If all the messages were filtered, both the original packet and the
  305. temporary file are deleted (this is often the case with those file attach
  306. messages from Tick).
  307.  
  308. The log file will contain full info on each packet processed, and on each
  309. message filtered (including the full message text).
  310.  
  311. NOTE THAT IF YOU FEED OTHER NODES, you will be filtering messages for them
  312. too. Since the packets are processed by MSFilter before your tosser gets
  313. ahold of them, filtered messages are kept from going to other nodes as
  314. well as yours.
  315.  
  316.  
  317. That's all folks!
  318. ~~~~~~~~~~~~~~~~~
  319. Well, that's all. Send comments/suggestions/bug reports/etc to Doug McLean
  320. at fido 1:255/9.0.
  321.  
  322. Doug
  323.  
  324.